\svnid{$Id: Content_Design.tex 206 2007-03-27 05:56:15Z shakes $}

\chapter{Specifications}
\paragraph{}
The Discrete Geometry (DG) Viewer will be a program that can easily allow the plotting of image, HDF5 and CSV files in both 2D and 3D (including surface plots). The program may then be easily expandable to do CT reconstructions snd medical imaging. The exact requirements of the viewer include:
\begin{enumerate}
\item
View image files supported by Qt or wxWidgets (whichever is chosen). Possibly extend this to other formats using an Image processing library.
\item
Support HDF5 and CSV file formats.
\item 
Show data of the file loaded in spreadsheet format and allow spreadsheet functionality.
\item 
Do 2D plots of row and column data in various forms.
\item
Support various transforms (such as FFTs and DRTs).
\item
Loading and functionality should be extremely light weight (like Scintilla but for imaging).
\item
Handle 3D plots (surface and others) using VTK plotting library.
\item
Allow multiple instances of each of the above and allow easy navigation.
\item
Allow the use of scripts and scripting. Should also have a console built-in based on Shell or Python.
\end{enumerate}

Once the above functionality has been provided for, the generating capabilities will be implemented. These include ways in which is visualise vectors on discrete arrays and other discrete geometry related ideas built during doctorate.

The core goals are:
\begin{enumerate}
\item 
Extremely Light Weight and Fast.
\item 
Easily work space allowing multiple instances of data and data visualisation.
\item 
Highly Scriptable, with a console back-end.
\item
Unique imaging features (especially those of the Discrete Projection Theory).
\end{enumerate}


\chapter{Design Approach}
\paragraph{}
In order to meet the core goals, the following will need to be done (in the order shown):
\begin{enumerate}
\item 
Due to the back-end requirement, it will need to be built first. It can either have the form of a python shell or a gnuplot like shell. Feasibility of both types need to be done.
\item
A prototype might be worth building to ensure all elements will and can work together.
\item 
The previous approach will ensure the system is light weight only if the shell is designed properly and modularised well. 
\item 
The GUI will have to be built thats also light weight and one that has flexibility for the desired type of work space.
\end{enumerate}

For the scripting environment, Python seems to be ideal as the C libraries can be wrapped using utilities like \emph{SIP} or \emph{SWIG} quite easily. The Python shell can be also integrated so it can be used interactively (and not just for scripting tasks for the program but anything else Python can do). A simple text editor can also be built-in as such \emph{Scintilla} to allow script building within the program. Shells arent easily available as modules in GUI toolkits like \emph{Qt} or \emph{wxWidgets}. Both have a python shell but the Qt version, \emph{QConsole} appears to be Linux only. The wxWidgets version doesnt really have good documentation. An alternative is to use \emph{iPython} Shell and integrate that but its writen in Python and wont be easily integrable unless Python versions of the GUI toolkits are used.

In any case, the data structures will need to be transfered between C and Python seemlessly. This will involve Python Interpreter API knowledge and programming. Something like \emph{Numpy} may have to be used as the common data structure medium thats fast enough. An alternative approach is to use \emph{Blitz++} and wrap the C code in C++, then use the Python wrappers for Blitz++ to provide the medium.

It may also be possible to build the application without any Python scripting (as a lot of effort will be required in wrapping custom Qt classes and the DGL library, as well as learning the Python API). One may build the application, the result being all Qt classes and DGL functions are completed and then wrap and add the scripting support. It may also be worth while putting image processing library integration and operations on hold until the purpose of the application becomes more clear. It should be easy to add operations once the main application is operational.

\chapter{Interfaces}
\paragraph{}
Different libraries will be required for difference tasks. The libraries currently being thought of are:
\begin{enumerate}
\item{Trolltech Qt Library}
- For the GUI related tasks. [MinGW/VC++/GCC]
\item{Qwt Sub-Library}
- For 2D plotting purposes. [MinGW/VC++/GCC]
\item{VTK}
- For 3D plotting purposes in Qt. [MinGW/VC++/GCC]
\item{ImageMagick/Magick++/VIPS}
- For image processing, must check whether VTK or Qt provide enough functionality.
\item{DGL}
- My Discrete geometry library. [MinGW/VC++/GCC]
\item{HDF5}
- For HDF5 file format support. [MinGW (not buildable)/VC++/GCC]
\item{Python API}
- For Python scripting support. [MinGW (not buildable)/VC++/GCC]
\item{QScintilla}
- For text editing support to enable easy scripting. 
\item{FFTW}
- For FFT support. [MinGW/VC++/GCC]
\end{enumerate}
Consequently, all libraries must be interfaced using a common array system. This should reduce the inter-communication of the libraries down to a trivial task of passing arrays to the correct functions. Candidates for such a system are the \emph{Blitz++} Numerical Array Library [MinGW/VC++/GCC], primitive C/C++ arrays and STL containers. Therefore, each of the above interfaces must be checked for feasibility with regards to interfacing, efficiency and speed.

\section{Array Interfaces}
\paragraph{}
The Blitz++ library is dynamic, multi-dimensional (tensorial) and fast array library. It is stored in a contiguous manner and can also be passed as a C primitive array to the FFTW library (which has already been used successfully). The Blitz++ Arrays are faster in computations and more flexible than STL containers, hence the STL containers are ruled out as a viable array interface. The primitive C/C++ are faster than the Blitz++ arrays and only dynamic (leakage and efficiency wise) when using C++\footnote{The C primitives (using pointers) are also dynamic but will be very messy.}. Also the multi-dimensional nature of files like HDF requires easy multi-dimensional support. Therefore, it is probably best to use Blitz++ Arrays are the interface. It is unknown however how a C/C++ primitive array can be passed into a Blitz++ Array efficiently.

\section{Interfacing VTK}
\paragraph{}
The following classes have been found to allow the interfacing of VTK:
\begin{enumerate}
\item{vtkImageData}
- "vtkImageData represents a geometric structure that is a topological and geometrical regular array of points". Data needs to extracted or imprinted from and to this object.
\item{vtkImageImport}
- "vtkImageImport provides methods needed to import image data from a source independent of VTK, such as a simple C array or a third-party pipeline". This will be used to imprint data into VTK.
\item{vtkImageExport}
- "vtkImageExport provides a way of exporting image data at the end of a pipeline to a third-party system or to a simple C array". This will be used to extract data from VTK.
\item{vtkImageViewer2}
- "vtkImageViewer2 is a convenience class for displaying a 2D image". Already provides a wrapping of image display using VTK. The example \emph{ /Examples/GUI/Qt/ImageViewer/main.cxx} demonstrates an image viewer built using Qt and VTK!
\end{enumerate}
As a side note, it seems VTk supports the following image formats - "Save images to various file formats including png, jpeg, tiff, bmp and ppm", as well as other data formats.

\section{Interfacing Magick++}
\paragraph{}
Qt and Magick++ can be interfaced in the following way (its required as Qt will be used for display):
\begin{verbatim}
/*
 * This function takes a QPixmap object and converts it into an ImageMagick
 * object, of class Image.  It does so by executing QPixmap::save(), but
 * into a buffer in memory instead of into the filesystem.  Then an
 * ImageMagick Blob object is created to reference the same data as the
 * QBuffer, and the Image is created from that.
 */
Image* createImageFromQPixmap ( QPixmap& p )
{
    QByteArray ba;
    QBuffer bu( ba );
    bu.open( IO_WriteOnly );
    p.save( &bu, "PNG" );
    Blob bl( ba.data(), ba.size() );
    Image* im = new Image( bl, Geometry(p.width(),p.height()), "png" );
    return im;
}
\end{verbatim}
Here the Blob class is able to return void type arrays and the Image class able to return Blobs. This allows the inverse to be done also. It is trivial to interface QPixmap class to Blitz++ Arrays using QImage class.

\section{Interfacing Others}
\paragraph{}
When interfacing with Qwt Library, the QwtPlot class uses C/C++ primitive arrays so Blitz++ can be easily used. FFTW is also able to use Blitz++ Arrays, as I have used this before. HDF5 also uses primitives arrays and won't be of any issue. The main issue will be whether the Blitz++ arrays are faster than QImage class and/or others and is it worth having a conversion/interfacing step in that case.

\chapter{Class Design}
\paragraph{}
In order to make the application has modular as possible, each critical element of the application has to be wrapped in a class. This includes:
\begin{enumerate}
 \item{Display of Images}
 - A class has to wrap the Qt imaging/display capabilities so that it may be replaced easily. [DQVImageDisplay]
 \item{Image Processing}
 - A class has to wrap the opertions used to that the image processing library can be replaced. [DQVImageProcessor]
 \item{2D/3D Plotting}
 - Again display operations have to be wrapped for each of the 2D and 3D libraries. [DGV2DPlot and DQV3DPlot]
 \item{Text Editor Support}
 - The library shouldnt need to be wrapped as the library is fairly modular already. [DGVEditor (QScintilla is already sufficient)]
 \item{Python Support}
 - Again the scripting element will have to be wrapped to allow replacement and removal. [DGVScripter]
\end{enumerate}

\chapter{Program Structure}
\paragraph{}
I believe it is essential to ensure that the program has the most modular structure as possible. It will be achieved by two methods. Firstly, the class structure will ensure that the underlying source components are modular. The second is assured by using a plugin system for the program. Qt fully supports plugin application building and what will most likely will the plugin system to be utilised. These are the main concerns of this chapter.

\section{Plugin Design}
\paragraph{}
The plugin structure and design will have to be based on the class design. The main components will have to be identified and the static and dynamic plugins determined. The main plugins will have to be static and the less major plugins will have to dynamic. The static plugins will be
\begin{enumerate}
 \item 
 The \emph{image display} within the program.
 \item
 The \textit{image data display} using spreadsheets.
 \item
 The \textit{fundamental transforms} on images.
 \item
 Image \textit{arithmetic}.
 \item
 Standard data format support.
\end{enumerate}
The dynamic plugins for the program will have to be
\begin{enumerate}
 \item 
 The \textit{image processin}g library or libraries.
 \item
 The 2D plotting for data.
 \item
 The 3D plotting for data.
 \item
 Support for \textit{HDF5} files.
 \item
 Support for \textit{FITS} files.
 \item
 The \textit{Python Interpreter} support for scripting.
 \item
 Text editor support for scripting.
 \item
 My DG Library
\end{enumerate}
The plugin system will also ensure that the program is efficient and smallest in size overall.

\chapter{Image Display - [DGVImageDisplay] Class}
\paragraph{}
This class' main purpose will be to display images of arbitrary ranges from various formats and display them in grey scale at least. Using QPixmap and QImage allows for displaying of standard image ranges (such as 8-bit grey scale) automatically, but fails for arbitrary ranges. This will have to be extended to display scientific images.
\begin{figure}[ht]
 \centering
 \includegraphics[width=0.35\textwidth]{./figs/DGVImage}
 \caption{DGVImage Class UML Diagram.}
 \label{fig::ClassUML}
\end{figure}


\section{Requirements}
\begin{enumerate}
 \item 
 The 8-bit grey scale must be calibrated to handle arbitrary ranges. This will involve using the setColor() functions to initialise the colour table.
 \item
 Functions will have to be created for determining the necessary ranges to achieve the previous requirement.
 \item
 Must be able to handle colour images. (This should already be provided for by QImage and QPixmap classes).
 \item
 Must be fast and memory efficient.
 \item
 Operations on images must be acccessible from a right click menu and menu bar.
\end{enumerate}

